add render-time and async node error recovery pattern by tmarmer · Pull Request #802 · player-ui/player

tmarmer · 2026-02-12T22:16:34Z

Update captureError to fail the player state if no error transition is available.
Implement render-time error recovery functionality
- iOS: Errors are handled during deserialization of asset data. Asset render functions do not support throwing so actual render-time issues do not need to be caught
- Android: Errors are caught for each asset type and bubble up according to their needs.
  - RenderableAsset: Bubbles up to PlayerFragment error handling which calls PlayerViewModel.fail which now uses the error controller.
  - SuspendableAsset: Errors caught in the coroutine exception handler are sent to the error controller (except for cancellation exceptions)
  - ComposableAsset: Errors thrown during deserialization are sent to the error controller.
- React: Top level ErrorBoundary on react player catches and sends errors to the ErrorController.
Add PlayerErrorMetadata interface for errors to implement to include info required for the error controller to capture errors
Add errors for specific areas where it can be brought to the error controller
- AssetRenderError updated to include metadata required for the error controller
- ResolverError added for errors thrown during computeTree
Update async-node plugin to make use of the above to call its onAsyncNodeError hook and replace broken content

Change Type (required)

Indicate the type of change your pull request is:

patch
minor
major
N/A

Does your PR have any documentation updates?

Updated docs
No Update needed
Unable to update docs

Release Notes

Update AsyncNodePlugin's onAsyncNodeError hook to depend on the ErrorController's onError hook for finding errors.
Capture render time errors using ErrorController.captureError and allow for error recovery on all platforms.
Add PlayerErrorMetadata interface across platforms and ensure serialization of errors keeps additional metadata.
- When throwing an error that matches this interface, the ErrorController.captureError will prefer data from the error object when calling the onError hook.

📦 Published PR as canary version: 0.15.1--canary.802.31569

Try this version out locally by upgrading relevant packages to 0.15.1--canary.802.31569

codecov · 2026-02-13T01:36:53Z

Codecov Report

❌ Patch coverage is 94.38356% with 41 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.36%. Comparing base (07bcf2a) to head (107cbfe).

Files with missing lines	Patch %	Lines
.../com/intuit/playerui/core/error/ErrorController.kt	66.66%	2 Missing and 5 partials ⚠️
plugins/async-node/core/src/index.ts	95.39%	7 Missing ⚠️
...e/serialization/serializers/ThrowableSerializer.kt	76.00%	3 Missing and 3 partials ⚠️
core/player/src/view/resolver/index.ts	93.65%	4 Missing ⚠️
react/player/src/player.tsx	95.87%	4 Missing ⚠️
.../com/intuit/playerui/core/player/HeadlessPlayer.kt	0.00%	3 Missing ⚠️
...e-assets/core/src/plugins/error-recovery-plugin.ts	90.32%	3 Missing ⚠️
core/player/src/controllers/view/controller.ts	87.50%	2 Missing ⚠️
...gins/async-node/core/src/utils/getNodeFromError.ts	91.30%	2 Missing ⚠️
core/player/src/controllers/error/controller.ts	95.83%	1 Missing ⚠️
... and 2 more

Additional details and impacted files

@@                 Coverage Diff                  @@
##           error-controller     #802      +/-   ##
====================================================
+ Coverage             86.02%   86.36%   +0.33%     
====================================================
  Files                   513      512       -1     
  Lines                 23566    24020     +454     
  Branches               2703     2828     +125     
====================================================
+ Hits                  20272    20744     +472     
+ Misses                 2956     2942      -14     
+ Partials                338      334       -4

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

codecov · 2026-02-13T02:52:25Z

Bundle Report

Changes will increase total bundle size by 125.88kB (2.17%) ⬆️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
plugins/beacon/core	422.87kB	5.4kB (1.29%) ⬆️
plugins/check-path/core	441.27kB	5.4kB (1.24%) ⬆️
plugins/stage-revert-data/core	404.89kB	5.4kB (1.35%) ⬆️
react/subscribe	13.68kB	2.04kB (17.56%) ⬆️
plugins/reference-assets/core	503.98kB	25.28kB (5.28%) ⬆️
react/player	84.12kB	10.77kB (14.69%) ⬆️
plugins/common-expressions/core	427.12kB	5.4kB (1.28%) ⬆️
plugins/markdown/core	681.95kB	5.41kB (0.8%) ⬆️
plugins/common-types/core	501.45kB	5.4kB (1.09%) ⬆️
plugins/metrics/core	459.43kB	5.4kB (1.19%) ⬆️
plugins/async-node/core	503.08kB	29.55kB (6.24%) ⬆️
core/player	1.02MB	20.4kB (2.04%) ⬆️

Affected Assets, Files, and Routes:

view changes for bundle: plugins/check-path/core

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`CheckPathPlugin.native.js`	5.4kB	411.78kB	1.33%

view changes for bundle: plugins/metrics/core

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`MetricsPlugin.native.js`	5.4kB	427.08kB	1.28%

view changes for bundle: react/subscribe

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`cjs/index.cjs`	739 bytes	5.74kB	14.77% ⚠️
`index.legacy-esm.js`	652 bytes	3.97kB	19.66% ⚠️
`index.mjs`	652 bytes	3.97kB	19.66% ⚠️

view changes for bundle: plugins/beacon/core

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`BeaconPlugin.native.js`	5.4kB	408.4kB	1.34%

view changes for bundle: plugins/markdown/core

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`MarkdownPlugin.native.js`	5.41kB	656.8kB	0.83%

view changes for bundle: react/player

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`cjs/index.cjs`	3.77kB	30.48kB	14.13% ⚠️
`index.legacy-esm.js`	3.5kB	26.82kB	15.0% ⚠️
`index.mjs`	3.5kB	26.82kB	15.0% ⚠️

view changes for bundle: core/player

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`Player.native.js`	6.33kB	425.01kB	1.51%
`cjs/index.cjs`	4.78kB	202.64kB	2.42%
`index.legacy-esm.js`	4.65kB	195.91kB	2.43%
`index.mjs`	4.65kB	195.91kB	2.43%

view changes for bundle: plugins/stage-revert-data/core

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`StageRevertDataPlugin.native.js`	5.4kB	398.06kB	1.38%

view changes for bundle: plugins/reference-assets/core

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`ReferenceAssetsPlugin.native.js`	18.32kB	467.12kB	4.08%
`cjs/index.cjs`	2.33kB	13.52kB	20.81% ⚠️
`index.legacy-esm.js`	2.31kB	11.67kB	24.73% ⚠️
`index.mjs`	2.31kB	11.67kB	24.73% ⚠️

view changes for bundle: plugins/async-node/core

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`AsyncNodePlugin.native.js`	14.66kB	440.33kB	3.44%
`cjs/index.cjs`	5.03kB	22.43kB	28.88% ⚠️
`index.legacy-esm.js`	4.93kB	20.16kB	32.42% ⚠️
`index.mjs`	4.93kB	20.16kB	32.42% ⚠️

view changes for bundle: plugins/common-expressions/core

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`CommonExpressionsPlugin.native.js`	5.4kB	405.88kB	1.35%

view changes for bundle: plugins/common-types/core

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`CommonTypesPlugin.native.js`	5.4kB	430.28kB	1.27%

tmarmer · 2026-02-13T14:29:12Z

/canary

intuit-svc · 2026-02-13T14:55:49Z

Build Preview

Your PR was deployed by CircleCI #31569 on Fri, 13 Feb 2026 14:55:49 GMT with this version:

0.15.1--canary.802.31569

📖 Docs (View site)

KetanReddy · 2026-03-10T19:01:59Z

core/player/src/controllers/error/controller.ts

+/** Returns a function to be used as the `replacer` for JSON.stringify that tracks and ignores circular references. */
+const makeJsonStringifyReplacer = (): ReplacerFunction => {
+  const cache = new Set();
+  return (_: string, value: any) => {
+    if (typeof value === "object" && value !== null) {
+      if (cache.has(value)) {
+        // Circular reference found, discard key
+        return "[CIRCULAR]";
+      }
+      // Store value in our collection
+      cache.add(value);
+    }
+    return value;
+  };
+};
+


Why do we need to do this? Shouldn't internal Player state be serializable?

The issue here stems from the ResolverError adding in the failed node in its metadata. We need a better solution but this was put in place to allow the metadata to get logged without throwing errors since the node itself has circular references.

If we don't want the node logged or set in the dataController as part of captureError we either need to not include the metadata in logs/data or we need another mechanism to identify resolver nodes with to avoid sending the whole object to keep its reference.

So this is so that the error includes the originating AST node, gotcha. I think a reference should be able to be stored fine in the Data Controller without serialization right? For logging can we just reference the asset ID?

If the error controller was aware of the metadata being logged we could, but because any error with any metadata could pass through it, we can't identify when we're getting something like a Node or a simpler object. That and sometimes the originating Node being logged might be an async node or something else that generated the asset.

core/player/src/controllers/error/types.ts

core/player/src/controllers/view/controller.ts

KetanReddy · 2026-03-10T19:04:59Z

core/player/src/view/resolver/types.ts

+export const ResolverStages = {
+  ResolveOptions: "resolve-options",
+  SkipResolve: "skip-resolve",
+  BeforeResolve: "before-resolve",
+  Resolve: "resolve",
+  AfterResolve: "after-resolve",
+  AfterNodeUpdate: "after-node-update",
+} as const;


Is there a way we can automate this?

Couldn't find a way to automatically form this object, but simplified the types here to use an enum. If you have any ideas here I'm open to try something else

plugins/reference-assets/core/src/assets/throwing/types.ts

react/player/src/__tests__/app.test.tsx

…if no transition available.

core/player/src/controllers/error/utils/__tests__/isErrorWithMetadata.test.ts

core/player/src/controllers/error/__tests__/middleware.test.ts

core/player/src/view/resolver/ResolverError.ts

Co-authored-by: Ketan Reddy <KetanReddy@users.noreply.github.com>

…etadata.test.ts Co-authored-by: Ketan Reddy <KetanReddy@users.noreply.github.com>

cehan-Chloe

.

… of async nodes on error

core/player/src/controllers/flow/flow.ts

…ed across the flow instance and error controller

KVSRoyal

iOS stuff lgtm---can you just double-check that everything public actually needs to be?

sugarmanz · 2026-03-26T22:36:24Z

android/player/src/main/kotlin/com/intuit/playerui/android/asset/AssetRenderException.kt

+    override val type: String
+        get() = ErrorTypes.RENDER
+    override val severity: ErrorSeverity?
+        get() = ErrorSeverity.ERROR
+    override val metadata: Map<String, Any?>?
+        get() = mapOf(
+            "assetId" to rootAsset.asset.id,
+        )


Since these are static, just assign them:

Suggested change

override val type: String

get() = ErrorTypes.RENDER

override val severity: ErrorSeverity?

get() = ErrorSeverity.ERROR

override val metadata: Map<String, Any?>?

get() = mapOf(

"assetId" to rootAsset.asset.id,

)

override val type: String = ErrorTypes.RENDER

override val severity: ErrorSeverity? = ErrorSeverity.ERROR

override val metadata: Map<String, Any?> = mapOf(

"assetId" to rootAsset.asset.id,

)

sugarmanz · 2026-03-26T22:40:47Z

jvm/core/src/main/kotlin/com/intuit/playerui/core/bridge/JSErrorException.kt

    cause: Throwable? = node.getSerializable("innerErrors", ListSerializer(ThrowableSerializer()))?.first(),
+    override val type: String = "",
+    override val severity: ErrorSeverity?,
+    override val metadata: Map<String, Any?>?,


I don't think these belong on the base JSErrorException type, as that is supposed to mirror the base Error TS class. We probably want a subclass that matches the PlayerErrorMetadata one

sugarmanz · 2026-03-26T22:42:19Z

jvm/core/src/main/kotlin/com/intuit/playerui/core/error/ErrorController.kt

 * Represents a Player error with metadata
 */
 @Serializable(with = PlayerErrorInfo.Serializer::class)
 public class PlayerErrorInfo internal constructor(


Should this whole class just be a PlayerException (with metadata) instance instead of a NodeWrapper? It could then just use the ThrowableSerializer instead of a whole new construct

I believe this type is meant to mimic this TS type, which is not an error itself. Maybe a rename would be helpful for clarity?

@cehan-Chloe any thoughts here?

+1 this mimic the core TS type. There is already a PlayerError in iOS and I would like to use same name in mobile to keep the consistency hence the renaming. agree it's kinda confusing maybe we can rename the PlayerError in iOS and use PlayerError in all platform if it's more clear.

sugarmanz · 2026-03-26T22:43:22Z

jvm/core/src/main/kotlin/com/intuit/playerui/core/player/HeadlessPlayer.kt

+        coroutineExceptionHandler =
+            config.coroutineExceptionHandler ?: CoroutineExceptionHandler { _, throwable ->
+                if (state !is ReleasedState) {
+                    logger.error("[HeadlessPlayer]: Error has been found")


Consolidate the two logs now — just pull the other one up if you think we should log it every time regardless of whether we can forward it to captureError.

Oh my bad, had some extra logs when testing and forgot to remove this >.<

sugarmanz · 2026-03-26T22:43:42Z

...src/test/kotlin/com/intuit/playerui/jsi/serialization/serializers/ThrowableSerializerTest.kt

+    override val type: String
+        get() = "TestError"
+    override val severity: ErrorSeverity?
+        get() = ErrorSeverity.ERROR
+    override val metadata: Map<String, Any?>?
+        get() = mapOf(
+            "testProperty" to "testValue",
+        )


Assign instead of getters

sugarmanz · 2026-03-26T22:44:43Z

jvm/testutils/src/main/kotlin/com/intuit/playerui/utils/test/PlayerTest.kt

+    public fun setupPlayer(
+        plugins: List<Plugin> = this.plugins,
+        runtime: Runtime<*> = this.runtime,
+        includeThisInPlugins: Boolean = true,


Rather than an extra param, should we just do this automatically if this isn't contained in plugins?

sugarmanz · 2026-03-26T22:45:44Z

.../async-node/jvm/src/test/kotlin/com/intuit/playerui/plugins/asyncnode/AsyncNodePluginTest.kt

+        val refPlugin = ReferenceAssetsPlugin()
+        refPlugin.apply(runtime)
+        if (player is HeadlessPlayer) {
+            val invokable = (player as HeadlessPlayer).node.getInvokable<Unit>("registerPlugin")


We should just implement registerPlugin properly than hack it into a test.

Agreed, but I think I want to avoid that here for the sake of not adding more scope to this PR. This was a hack anyway to get around some issues the tests had with the ReferenceAssetsPlugin. I made some changes earlier that make it so this hack isn't needed and missed updating the tests. For now, I've removed any resgisterPlugin code from the tests.

Ideally I would like to remove that dependency on another plugin to test the AsyncNodePlugin but it seems like there is no easy way to decouple it in these tests so I might look to do that later as well.

sugarmanz · 2026-03-26T22:46:20Z

.../async-node/jvm/src/test/kotlin/com/intuit/playerui/plugins/asyncnode/AsyncNodePluginTest.kt

        }

-        val errorMessage = assertThrows<Exception> {
+        val refPlugin = ReferenceAssetsPlugin()


Isn't this already applied on the Player instance?

nancywu1

iOS changes looks good, do we have any examples/mocks in the demo app with errorTransitions or error state structure, if not maybe can add them in later?

add asset error recovery via asyncNodePlugin on web and android

983989f

tmarmer requested review from a team as code owners February 12, 2026 22:16

tmarmer added 3 commits February 12, 2026 18:19

fix test errors

68a9169

fix async test

7ae30a5

comment last broken test for now

17ce531

intuit-svc added a commit to player-ui/player-ui.github.io that referenced this pull request Feb 13, 2026

Deploying docs for player-ui/player#802

1c9a8e5

finish ios implementation of error recovery

0946e3b

tmarmer requested a review from a team as a code owner February 24, 2026 21:45

add errors with metadata to error controller on react and android

f81c0f0

tmarmer marked this pull request as draft March 10, 2026 18:57

KetanReddy reviewed Mar 10, 2026

View reviewed changes

core/player/src/controllers/error/types.ts Outdated Show resolved Hide resolved

KetanReddy reviewed Mar 10, 2026

View reviewed changes

core/player/src/controllers/view/controller.ts Show resolved Hide resolved

KetanReddy reviewed Mar 10, 2026

View reviewed changes

plugins/reference-assets/core/src/assets/throwing/types.ts Outdated Show resolved Hide resolved

KetanReddy reviewed Mar 10, 2026

View reviewed changes

react/player/src/__tests__/app.test.tsx Outdated Show resolved Hide resolved

tmarmer added 8 commits March 11, 2026 11:53

re-enable react player test. fail player state from error controller …

76aaf30

…if no transition available.

update ResolverStage to be an enum

cf65e8b

fix android build errors

b0b9db2

finish ios error recovery implementation

81dc14e

format kt and add ts tests

06a8f7f

fix mock package build

163389d

fix throwable serializer. Improve react state management during errors

50f552c

remove throwing asset. fix error severity in jvm

103a405

KetanReddy reviewed Mar 20, 2026

View reviewed changes

core/player/src/controllers/error/utils/__tests__/isErrorWithMetadata.test.ts Outdated Show resolved Hide resolved

KetanReddy reviewed Mar 20, 2026

View reviewed changes

core/player/src/controllers/error/__tests__/middleware.test.ts Outdated Show resolved Hide resolved

KetanReddy reviewed Mar 20, 2026

View reviewed changes

core/player/src/view/resolver/ResolverError.ts Show resolved Hide resolved

tmarmer and others added 4 commits March 23, 2026 11:24

Update core/player/src/controllers/error/utils/isErrorWithMetadata.ts

d429e81

Co-authored-by: Ketan Reddy <KetanReddy@users.noreply.github.com>

Update plugins/async-node/core/src/utils/getNodeFromError.ts

88ba90b

Co-authored-by: Ketan Reddy <KetanReddy@users.noreply.github.com>

Update core/player/src/controllers/error/utils/__tests__/isErrorWithM…

c095a6d

…etadata.test.ts Co-authored-by: Ketan Reddy <KetanReddy@users.noreply.github.com>

make resolvererror public in player core

7c3194b

cehan-Chloe reviewed Mar 23, 2026

View reviewed changes

tmarmer added 8 commits March 23, 2026 15:20

update reference asset plugin tests

43aca17

update error middleware to export binding prefix

6382c75

add tests for useSubscriber hook

3624db1

fix eslint error

c67821b

update testing for async node plugin. fix issue with recursive search…

a75ceb1

… of async nodes on error

add react player tests for error handling

d2946fe

add error tests for resolver changes

702e789

fix test and lint errors

dd4573e

cehan-Chloe reviewed Mar 25, 2026

View reviewed changes

core/player/src/controllers/flow/flow.ts Outdated Show resolved Hide resolved

tmarmer added 4 commits March 25, 2026 13:09

update lockfile

37c86f4

add additional throwable serializer tests for new functionality

d48a5a5

replace hasErrorTransition function with getErrorTransitionState reus…

a98ff7d

…ed across the flow instance and error controller

update error docs for async node plugin

56817bf

tmarmer changed the title ~~[WIP]: render-time error recovery~~ add render-time and async node error recovery pattern Mar 25, 2026

tmarmer marked this pull request as ready for review March 25, 2026 20:34

tmarmer requested a review from a team as a code owner March 25, 2026 20:34

tmarmer added 2 commits March 25, 2026 16:51

format kt files to fix lint issues

73cbfe2

ignore jvm testutils in codecov report

107cbfe

KVSRoyal approved these changes Mar 26, 2026

View reviewed changes

sugarmanz requested changes Mar 26, 2026

View reviewed changes

nancywu1 approved these changes Mar 27, 2026

View reviewed changes

separate JSError class in kt and code cleanup

83a18a3

Conversation

tmarmer commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Change Type (required)

Does your PR have any documentation updates?

Release Notes

Uh oh!

codecov bot commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

codecov bot commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle Report

Affected Assets, Files, and Routes:

Assets Changed:

Assets Changed:

Assets Changed:

Assets Changed:

Assets Changed:

Assets Changed:

Assets Changed:

Assets Changed:

Assets Changed:

Assets Changed:

Assets Changed:

Assets Changed:

Uh oh!

tmarmer commented Feb 13, 2026

Uh oh!

intuit-svc commented Feb 13, 2026

Build Preview

📖 Docs (View site)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cehan-Chloe left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

KVSRoyal left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

tmarmer commented Feb 12, 2026 •

edited

Loading

codecov bot commented Feb 13, 2026 •

edited

Loading

codecov bot commented Feb 13, 2026 •

edited

Loading

cehan-Chloe left a comment •

edited

Loading